CXX-3082 Add comprehensive examples (mongocxx, Part 2) #1236
+1,573
−55
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Resolves CXX-3082. Followup to #1216. Verified by this patch.
Adds examples for the remaining items listed in the description of #1216:
Additionally adds examples for index views (not to be confused with Atlas Search Indexes or Queryable Encryption Range Indexes) as part of Collection examples.
Deferred / Out of Scope
The following headers do not have an API example due to redundancy (their usage may follow a similar pattern to an existing representative example). Users may reference the API documentation to learn how to use said interfaces instead.
The following headers do not have an API example due to deliberately being excluded from the current scope of work (their implementation requires significant effort and complexity, or an example of its usage is not expected to be necessary). These may be revisited in the future.
The following headers do not have an API example due to the expectation of eventual deprecation-and-removal, to encourage use of alternative patterns, or because they are simply unused. (In particular, concerning CXX-834 for the current exception class hierarchy.)
In light of CXX-834,
mongocxx::exceptionis used/encouraged as much as possible, withmongocxx::operation_exceptionused only when access to raw server error information is required. All other exception classes are deliberately not referenced in the API examples.Note
Error handling for exceptions (that are not
operation_exception) thrown by specific interfaces which are considered redundant or out-of-scope by this PR are deferred to API documentation. These examples are intended to be comprehensive, but not exhaustive.API Examples Runner
The runner now supports disabling use of
fork()on invocation even if the feature is enabled. This flag (combined with--jobs 1) is expected to help improve the debugging experience of API examples (execution on a single process and a single thread).DB Lock
The DB Lock class learned to use "majority" read/write concern when dropping the collection to better support reliability and consistency of examples when run against replica sets and sharded clusters. The class also learned to avoid violating database name length limitations by clipping the front of the example component name (used as a unique database name in many examples) to remain within 63 characters.
Specific Workarounds
Several examples require extra considerations to remain compatible with server topologies and/or execution environments. These include:
mongocryptdURI+mongocryptdSpawnArgsin the auto encryption options example to avoid the spawned mongocryptd instance from stepping over a port (27020) in use by a sharded cluster (mongos on 27017 and 27018, a config server on 27019, and at least one mongod on 27020 through 27020 + N).